home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / pc / DirectX SDK / DXSDK / samples / Multimedia / DirectShow / Players / DDrawXCL / readme.txt < prev    next >
Encoding:
Text File  |  2001-10-10  |  7.9 KB  |  160 lines
  1. DirectShow Sample -- DDrawXCL
  2. -----------------------------
  3.  
  4.  
  5.             DirectDraw Exclusive Mode Video Playback Capability
  6.             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  7.  
  8.  
  9. General Information:
  10. ====================
  11. Now video can be played back from AVI, MPEG files as well as DVD titles
  12. even in DirectDraw exclusive fullscreen mode.  This is expected to be
  13. very helpful to games and interactive content development.
  14.  
  15. The DirectX SDK includes various components that together
  16. offer this capability.  An updated Overlay Mixer filter in DirectShow
  17. is now capable of using a DirectDraw object and primary surface provided
  18. by an application, rather than insisting on using its own.
  19.  
  20. A new COM interface, IDDrawExclModeVideo, has been added on the Overlay 
  21. Mixer filter which allows applications to specify DirectDraw parameters
  22. and playback position, size, etc.  An app can do QueryInterface() on the
  23. Overlay Mixer filter to get the interface.  This interface is fully 
  24. documented in the SDK help documentation.
  25.  
  26. Also another new COM interface, IDDrawExclModeVideoCallback, has been
  27. defined in the SDK.  An application should implement an object that supports
  28. this interface to have a notification set up with the OverlayMixer about
  29. any changes to the overlay size, position, color key, etc. This callback
  30. mechanism allows any color key flashes and/or strips to be avoided.
  31.  
  32. We have also updated the DVD graph builder object and some methods of the
  33. IDvdGraphBuilder interface which allows applications to use the updated
  34. DVD graph builder object to pass the DirectDraw-related information to the
  35. Overlay Mixer for use in DVD playback filter graph building operation.
  36. Using a couple of other methods available on the IDDrawExclModeVideo
  37. interface, applications can get the color key information for
  38. superimposing graphics on top of video playing in the background. All of
  39. these changes have been fully documented in the SDK help.
  40.  
  41. A sample application, DDrawXcl, has also been added to the SDK samples.
  42. This application consists of:
  43.  
  44. * A DirectDraw object (DDrawObj.h, .cpp) that wraps all DirectDraw 
  45. functionality using IDirectDraw* COM interfaces as well as the
  46. IDDrawExclModeVideo interface.
  47.  
  48. * A video playback object (VidPlay.h, .cpp) that implements the details
  49. of building a filter graph to play AVI/MPEG files as well as DVD titles.
  50.  
  51. * An overlay notification sink object that receives the overlay change
  52. related callbacks from OverlayMixer and takes appropriate actions.
  53.  
  54. * A Windows application that uses the above objects to:
  55.  
  56.   - Go into fullscreen exclusive mode, switch to 800x600x8 (we just chose
  57.     one particular mode), and create a primary surface with one back buffer.
  58.  
  59.   - Build a filter graph to playback the selected type of video using
  60.     the DirectDraw object and surface provided by the application,
  61.     starts playing it and sets a timer to fire every 0.1 second.
  62.  
  63.   - On the timer event, the application draws color key of the required 
  64.     dimension on the back buffer, draws a ball that can be moved using 
  65.     keystrokes, draws an updated number of flips completed, and flips the
  66.     surfaces.
  67.  
  68.   - The callback notification object informs the DDraw object when color
  69.     keying of the video area should be started/stopped.
  70.  
  71. This is one of the basic requirements for games and interactive 
  72. content to play video using DirectShow inside the application.
  73.  
  74.  
  75.  
  76. The Limitations/Rules:
  77. ======================
  78. 1. The sequence of calls to get the application-created DirectDraw parameters
  79. to be used by OverlayMixer is as follows --
  80.  
  81.    For DVD:
  82.    - create the DVD graph builder object
  83.    - call IDvdGraphBuilder::GetDvdInterface() for IDDrawExclModeVideo
  84.      interface. This returns the IDDrawExclModeVideo interface of the
  85.      OverlayMixer in the DVD playback filter graph.
  86.    - call IDDrawExclModeVideo::SetDDrawObject() to set the DDraw object
  87.    - call IDDrawExclModeVideo::SetDDrawSurface() to set the DDraw surface
  88.    - call IDvdGraphBuilder::RenderDvdVideoVolume() to build a DVD graph
  89.    - call IDvdGraphBuilder::GetDvdInterface() to get a IMixerPinConfig(2)
  90.      interface pointer to the FIRST (only) input pin of the OverlayMixer.
  91.    - get color key info using IMixerPinConfig(2)::GetColorKey() 
  92.      method.  Also set the aspect ratio mode to stretching from the
  93.      default letter box mode of the OverlayMixer.
  94.    - call IDDrawExclModeVideo::SetCallbackInterface() with the pointer to the
  95.      object implementing the IDDrawExclModeVideoCallback interface.
  96.    - get the native video size and aspect ratio through
  97.      IDDrawExclModeVideo::GetNativeVideoProps() method, transform the width
  98.      and height based on the retrieved aspect ratio, and set the final video
  99.      size and position using IDDrawExclModeVideo::SetDDrawParameters() method.
  100.  
  101.    For AVI/MPEG:
  102.    - create an empty filter graph
  103.    - call IGraphBuilder::RenderFile() on the specified file to build graph.
  104.    - instantiate the OverlayMixer filter and add it to the graph.
  105.    - call IDDrawExclModeVideo::SetDDrawObject()
  106.    - call IDDrawExclModeVideo::SetDDrawSurface()
  107.    - connect the decoded video to the Overlay Mixer's first input pin
  108.    - remove the Video Renderer filter as it's a windowless playback case.
  109.    - get IMixerPinConfig(2) interface from the first input pin of the
  110.      OverlayMixer to get the color key through GetColorKey() method.
  111.      Also set the aspect ratio mode to stretching from the default letter box 
  112.      mode of the OverlayMixer.
  113.    - call IDDrawExclModeVideo::SetCallbackInterface() with the pointer to the
  114.      object implementing the IDDrawExclModeVideoCallback interface.
  115.    - get the native video size and aspect ratio through
  116.      IDDrawExclModeVideo::GetNativeVideoProps() method, transform the width
  117.      and height based on the retrieved aspect ratio, and set the final video
  118.      size and position using IDDrawExclModeVideo::SetDDrawParameters() method.
  119.  
  120. 2. The object implementing IDDrawExclModeVideoCallback interface has been
  121. kept very simple.  It stops color keying of the video area on the back buffer
  122. when it gets the OnUpdateOverlay() call with input parameter bBefore=TRUE.
  123. The color keying is turned on again on getting another OnUpdateOverlay() call
  124. with bBefore=FALSE and with the dwFlags indicating that the overlay is visible.
  125.  
  126. 3. The SetDDraw*() methods can be called only when the pins of the Overlay
  127. Mixer are not connected.  Otherwise, the calls will fail.
  128.  
  129. 4. The application has to draw colorkey at the right position on the (back 
  130. buffer of the) primary surface to get the video to appear. In the exclusive 
  131. mode, the Overlay Mixer doesn't draw color key at all.
  132.  
  133. 5. For DVDs, the subpicture and line21 (closed caption) data are intentionally
  134. not rendered in the exclusive mode. The DVD graph builder will not return
  135. S_FALSE for this only.
  136.  
  137.  
  138.  
  139. Known Issues:
  140. =============
  141. 1. The ball drawn on top of the video only moves when an arrow key is 
  142. pressed AND released.  Holding the arrow key down doesn't move the ball.
  143. This was a conscious decision made for the sample application.
  144.  
  145. 2. The application stops playing the video and tears down the filter graph 
  146. when it switches to non exclusive mode on getting an Alt-Tab keystroke. The
  147. playback is not resumed on activating the application.
  148.  
  149. 3. The application fills the whole back buffer with black color and then
  150. Blts the color key to the target video rectangle. This is not required unless
  151. the video is continually changing position. For video playing at the same
  152. position, just erasing the previous position of the ball with color key 
  153. should be sufficient. The comment at the top of the CDDrawObject::FillSurface()
  154. method should hopefully not cause any confusion.
  155.  
  156. 4. Some AVI files (MS-CRAM, Duck compressed) fail to connect to the 
  157. OverlayMixer filter on some display cards.  This causes the sample app to
  158. fail in building the graph. As a result, such files cannot be played back on
  159. some systems.
  160.